package com.feixiang.springbootinit.service;

/**
 * 文件存储服务接口，支持本地存储、云存储等多种实现
 */
public interface FileStorageService {

    /**
     * 存储文件（从企微SDK下载并保存）
     * @param sdk SDK实例（企微会话存档SDK）
     * @param sdkFileId 企微SDK返回的文件ID
     * @param md5Sum 文件MD5值（用于去重和命名）
     * @param fileExt 文件扩展名（如png、mp3）
     * @param subDir 存储子目录（如image/voice/file，用于分类）
     * @return 存储后的文件相对路径（用于生成访问URL）
     * @throws Exception 下载或存储失败时抛出异常
     */
    String storeFile(long sdk, String sdkFileId, String md5Sum, String fileExt, String subDir) throws Exception;

    /**
     * 根据存储路径获取文件访问URL
     * @param storedPath storeFile方法返回的文件路径
     * @return 可直接访问的URL（如/image/2024/0721/xxx.png）
     */
    String getFileUrl(String storedPath);

    /**
     * 检查文件是否已存在（避免重复下载）
     * @param md5Sum 文件MD5值
     * @param fileExt 文件扩展名
     * @param subDir 存储子目录
     * @return true-已存在，false-不存在
     */
    boolean isFileExists(String md5Sum, String fileExt, String subDir);

    /**
     * 删除文件（用于清理过期文件）
     * @param storedPath 存储路径
     * @return true-删除成功，false-删除失败或文件不存在
     */
    boolean deleteFile(String storedPath);
}